docs/development/Building in Linux.md

   1 # Generic Linux development tools
   2 ## Overview
   3
   4 This article endeavours to provide a generic guide for compiling INAV on Linux for INAV 2.6 and later.
   5
   6 INAV requires a reasonably modern `gcc-arm-none-eabi` cross-compiler. Different Linux distros will provide different versions of the cross-compiler. This will range from obsolete versions (e.g. Debian, Ubuntu LTS) to the latest stable release (Arch Linux).
   7
   8 In order to provide a uniform and reasonably modern cross compiler, INAV provides for the installation of a "known good / working" cross compiler, as well as a mechanism to override this if your distro provides a more modern option (e.g Arch Linux). In general, from a security perspective, Linux distros discourage the installation of software from sources other than the official distribution repositories and  'approved' sources (Ubuntu PPA, Arch AUR). The INAV approach of providing a recommended compiler is however both sound and justified:
   9
  10 * The cross-compiler is installed from a reputable source (ARM, the company that makes the CPUs used in our flight controllers)
  11 * Disto cross-compilers are often older than the recommended INAV compiler
  12 * The installed cross-compiler is only used to build INAV and it not obviously / generally available outside of the INAV build environment.
  13
  14 There are a however some specific cases for using the distro cross-compiler in preference to that installed by INAV:
  15
  16 * You are using a distro that installs a more modern compiler (Arch)
  17 * You are using a host platform for which ARM does not provide a compiler (e.g. Linux ia32).
  18
  19 ## Prerequisites
  20
  21 In addition to a cross-compiler, it is necessary to install some other tools:
  22
  23 * `git`  : clone and manage the INAV code repository
  24 * `cmake` : generate the build environment
  25 * `make` : run the firmware compilation
  26 * `ruby` : build some generated source files from JSON definitions
  27 * `gcc` : native compiler used to generate settings and run tests
  28
  29 Note that INAV requires `cmake` version 3.13 or later; any distro that provides `cmake` 3.13 will also provide adequate versions of the other tools.
  30
  31 Note also that Ubuntu 18.04 LTS does NOT provide a modern enough `cmake`; it is recommended that you upgrade to Ubuntu 20.04 LTS which does.
  32
  33 Note that you may prefer to use `ninja` rather than `make` as the build manager. This is described [below](#building-with-ninja).
  34
  35 ### Ubuntu / Debian
  36 ```
  37 # make sure the system is updated first
  38 sudo apt update && sudo apt upgrade
  39 sudo apt install git make ruby cmake gcc
  40 ```
  41
  42 ### Fedora
  43 ```
  44 # make sure the system is updated first
  45 sudo dnf -y update
  46 sudo dnf install git make ruby cmake gcc
  47 ```
  48
  49 ### Arch
  50 ```
  51 # make sure the system is updated first
  52 sudo pacman -Syu
  53 sudo pacman -S git make ruby cmake gcc
  54 ```
  55
  56 Once these prerequisites are installed, we can clone the repository to provide a local instance of the INAV source code.
  57
  58 ## Cloning the repository
  59 ```
  60 git clone https://github.com/iNavFlight/inav.git
  61 ```
  62
  63 Note: If you have a Github account with registered ssh key you can replace the `git clone` command with  `git clone git@github.com:iNavFlight/inav.git` instead of the https link.
  64
  65 The `git clone` creates an `inav` directory; we can enter this directory, configure the build environment and build firmware.
  66
  67
  68 ## Build tooling
  69
  70 For 2.6 and later, INAV uses `cmake` as its primary build tool. `cmake` simplifies various platform and hardware dependencies required to cross compile multiple targets. `cmake` still uses GNU `make` to invoke the actual compiler. It is necessary to configure the build environment with `cmake` before we can build any firmware.
  71
  72 ## Using `cmake`
  73
  74 The canonical method of using `cmake` is to create a `build` directory and run the `cmake` and `make` commands from within the `build` directory. So, assuming we've cloned the firmware repository into an `inav` directory, we can issue the following commands to set up the build environment.
  75
  76 ```
  77 cd inav
  78 # first time only, create the build directory
  79 mkdir build
  80 cd build
  81 cmake ..
  82 # note the "..", this is required as it tells cmake where to find its ruleset
  83 ```
  84
  85 `cmake` will check for the presence of an INAV-embedded cross-compiler; if this cross-compiler is not found it will attempt to download the vendor (ARM) GCC cross-compiler.
  86
  87 Note. If you want to use your own cross-compiler, either because you're running a distro (e.g. Arch Linux) that ships a more recent cross-compiler, or you're on a platform for which ARM doesn't provide a cross-compiler (e.g. 32bit Linux), the you should run the `cmake` command as:
  88
  89 ```
  90 cmake -DCOMPILER_VERSION_CHECK=OFF ..
  91 ```
  92
  93 `cmake` will generate a number of files in your `build` directory, including a cache of generated build settings `CMakeCache.txt` and a `Makefile`.
  94
  95 ## Bulding the firmware
  96
  97 Once `cmake` has generated the `build/Makefile`, this `Makfile` (with `make`) is used to build the firmware, again from the `build` directory. It is not necessary to re-run `cmake` unless the INAV cmake configuration is changed (i.e. a new release) or you wish to swap between the ARM SDK compiler and a distro or other external compiler.
  98
  99 The generated `Makefile` uses different a target selection mechanism from the older (pre 2.6) top level `Makefile`; you can generate a list of targets with `make help` (or, as the list is extremely long), pipe this into a pager, e.g. `make help | less`.
 100
 101 Typically, to build a single target, just pass the target name to `make`; note that unlike earlier releases, `make` without a target specified will build **all** targets.
 102
 103 ```
 104 # Build the MATEKF405 firmware
 105 make MATEKF405
 106 ```
 107
 108 One can also build multiple targets from a single `make` command:
 109
 110 ```
 111 # parallel build using all but 1 CPU core
 112 make -j $(($(nproc)-1)) MATEKF405 MATEKF722
 113 ```
 114
 115 The resultant hex file are in the `build` directory.
 116
 117 You can then use the INAV Configurator to flash the local `build/inav_x.y.z_TARGET.hex` file, or use `stm32flash` or `dfu-util` directly from the command line.
 118
 119 [msp-tool](https://github.com/fiam/msp-tool) and [flash.sh](https://github.com/stronnag/mwptools/blob/master/docs/MiscTools.asciidoc#flashsh) provide / describe 3rd party helper tools for command line flashing.
 120
 121 ### Cleaning
 122
 123 You can clean out the built files, either for all targets or selectively; a selective clean target is simply defined by prefixing the target name with `clean_`:
 124
 125 ```
 126 # clean out every thing
 127 make clean
 128 # clean out single target
 129 make clean_MATEKF405
 130 # or multiple targets
 131 make clean_MATEKF405  clean_MATEKF722
 132 ```
 133
 134 ### `cmake` cache maintenance
 135
 136 `cmake` caches the build environment, so you don't need to rerun `cmake` each time you build a target. Two `make` options are provided to maintain the `cmake` cache.
 137
 138 * `make edit_cache`
 139 * `make rebuild_cache`
 140
 141 It is unlikely that the typical user will need to employ these options, other than perhaps to change between the embedded ARM and distro compilers.
 142
 143 ## Building with ninja
 144
 145 `cmake` is not a build system, rather it generates build files for a build manager. The examples above use `make` as the build manager; this has been the legacy way of building INAV. It is also possible to use other build systems; one popular cross-platform tool is [ninja](https://ninja-build.org/) which is both lightweight and executes parallel builds by default.
 146
 147 * Install `ninja` from the distro tool (apt, dnf, pacman as appropriate)
 148 * Configure `cmake` to use `ninja` as the build system
 149
 150   ```
 151   cd build
 152   # add other cmake options as required.
 153   cmake -GNinja ..
 154   ```
 155
 156 * Then use `ninja` in place of `make` to perform the build
 157
 158   ```
 159   ninja MATEKF405 MATEKF722
 160   ```
 161
 162 ## Updating and rebuilding
 163
 164 In order to update your local firmware build:
 165
 166 * Navigate to the local INAV repository
 167 * Use the following steps to pull the latest changes and rebuild your local version of INAV firmware from the `build` directory:
 168
 169 ```
 170 $ cd inav
 171 $ git pull
 172 $ cd build
 173 $ ninja <TARGET>
 174 $ ## or make <TARGET>
 175 ```
 176
 177 ## Advanced Usage
 178
 179 For more advanced development information and `git` usage, please refer to the [development guide](https://github.com/iNavFlight/inav/blob/master/docs/development/Development.md).
 180
 181 ## Unsupported platforms
 182
 183 If you're using a host platform for which Arm does not supply a cross-compiler (Arm32, IA32), and the distro either does not package a suitable compiler or it's too old, then you can usually find a suitable compiler in the [xpack devtools collection](https://github.com/xpack-dev-tools/arm-none-eabi-gcc-xpack).
 184
 185 You will need to configure `cmake` to use the external compiler.